Inside Macintosh: QuickDraw GX Programmer's Overview / Part 1 - Getting Started With QuickDraw GX

Chapter 1 - An Introduction to QuickDraw GX

The Programming Experience

In addition to providing services to your application during runtime, QuickDraw GX provides many services and conveniences to you during application development time. The next few sections discuss how QuickDraw GX supports the programming and debugging processes.

Programming

QuickDraw GX provides many programming conventions and tools that make programming with QuickDraw GX easier. The next few sections discuss
these features.

The next section, "Programming Conventions," describes the programming conventions and naming consistencies used throughout the QuickDraw GX application programming interface.

The section after that, "Programming Utilities," introduces some QuickDraw GX programming tools that provide built-in support for some common program-
ming tasks.

The section "Sample Libraries," on page 35, discusses some of the sample code provided with the QuickDraw GX Software Development Kit.

Programming Conventions

The QuickDraw GX programming environment provides many consistent features and conventions to make software development more convenient and efficient. Some examples are:

• Object behavior. Setting and examining the properties of objects works consistently for all object types. You can explicitly move any shape object or supporting object into or out of memory. You can associate application-
  specific information with almost every type of object. In addition, you can create, copy, clone, and dispose of almost every type of object.
• Constant and data type names. Identifiers for constants and data types defined by QuickDraw GX begin with a lowercase gx.
• Function names. With few exceptions, QuickDraw GX functions start with the letters GX. Functions that create new objects always begin with GXNew; functions that dispose of objects always begin with GXDispose; and so on.
• Function results. Most QuickDraw GX functions return object references rather than error codes so that you can nest calls to QuickDraw GX functions; these functions return nil as the function result if an error occurs.
• Function parameters. The first parameter to a function is usually the object acted upon. Parameters named source are never modified by a function. Parameters named target may be modified.

This list contains only a few examples; there are many more discussed throughout this book and elsewhere in the QuickDraw GX suite of books, especially in the Inside Macintosh: QuickDraw GX Objects book.

Programming Utilities

In addition to the great number of QuickDraw GX-provided data types and functions you can use to create, manipulate, and render graphics and typo-
graphic shapes, QuickDraw GX also provides sets of support functions. QuickDraw GX uses these functions and data types internally and you can
use them, too. Some examples are:

• Mathematics. QuickDraw GX provides types for different representations
  of numbers--for example, fixed point and wide--as well as functions for manipulating these numbers. QuickDraw GX also provides a random number generator, matrix arithmetic, and other mathematical functions.
• Collections. QuickDraw GX provides the Collection Manager--a set of data types and functions that allow your application to store variable-length lists of variable-length data.
• Messages. Similarly, QuickDraw GX provides the Message Manager--a piece of system software that allows your application to install message handlers that receive system messages, and also allows your application to send messages of its own.

Sample Libraries

The QuickDraw GX Software Development Kit includes a vast library of sample code. Some of this sample code is in the form of sample applications that show you how to solve specific graphics programming problems. Some of this sample code comprises the QuickDraw GX graphics libraries. These libraries include functions that you might find helpful when writing your application. Since the code is provided, you can examine it and alter it to fit your applica-
tions needs. Some examples of graphics libraries are:

• The color library, which defines a set of commonly used colors that you can use when specifying the color of a graphics or typographic shape.
• The offscreen library, which provides data types and functions you can use to create offscreen buffers to smooth out your application's onscreen redrawing.
• The oval library, which contains functions that use path shapes to create ovals and circles.
• The ramp library, which contains functions you can use to create ramp shapes, also called gradiated fills--shapes that blend smoothly from one color
  to another.
• The shape controls library, which contains functions you can use to provide
  a user interface that allows your user to manipulate the mapping (scaling, skewing, rotation, and so on) of shapes.

This list contains only a few examples; there are many more graphics libraries that provide useful functions as well as illustrative programming examples.

Debugging

Along with the features designed to help you program with QuickDraw GX are many services designed to help you during the debugging phase of develop-
ment. Figure 1-11 shows an overview of the elements that make up the QuickDraw GX debugging environment.

Figure 1-11 Elements of the QuickDraw GX debugging environment

Debugging Version

The debugging version of the QuickDraw GX system extension provides many services to help you debug your graphics code. Some examples are:

• Errors, warnings, and notices. The debugging version of QuickDraw GX graphics and typography uses a sophisticated, three-level system of reporting diagnostic messages to your application.
• Drawing errors. A special type of error, a drawing error specifies why a particular shape might not have drawn correctly. If you find a shape that
  is not drawing, or is giving you an unexpected result, you can call a QuickDraw GX function that posts a descriptive error message to help
  you determine what went wrong.
• Type validation. With the debugging version, you can specify that QuickDraw GX check the parameters you send to QuickDraw GX
  functions to ensure that they are of the right type. You can also specify
  that QuickDraw GX do even more extensive type validation.

GraphicsBug

Both the debugging and non-debugging versions of QuickDraw GX support the GraphicsBug utility, the symbolic debugger for QuickDraw GX applica-
tions. GraphicsBug is similar to MacsBug and the two debuggers work together to provide a complete debugging environment for QuickDraw GX. You can also use the debugger of your choice in place of MacsBug.

You use the GraphicsBug debugger to examine the contents of QuickDraw GX shape objects and their supporting objects.

Chapter 2, "A Quick & Easy Sample Program," gives an examples of program-
ming with QuickDraw GX and shows how you can use the GraphicsBug debugger to examine the internal structures of QuickDraw GX objects.